---

FLAC/stream_decoder.h: stream decoder interface
[FLAC/_decoder.h: decoder interfaces]

This module contains the functions which implement the stream decoder. More...

Compounds
struct	FLAC__StreamDecoder
Typedefs
typedef FLAC__StreamDecoderReadStatus(*	FLAC__StreamDecoderReadCallback )(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data)
typedef FLAC__StreamDecoderWriteStatus(*	FLAC__StreamDecoderWriteCallback )(const FLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 *const buffer[], void *client_data)
typedef void(*	FLAC__StreamDecoderMetadataCallback )(const FLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data)
typedef void(*	FLAC__StreamDecoderErrorCallback )(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data)
Enumerations
enum	FLAC__StreamDecoderState {   FLAC__STREAM_DECODER_SEARCH_FOR_METADATA = 0, FLAC__STREAM_DECODER_READ_METADATA, FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC, FLAC__STREAM_DECODER_READ_FRAME,   FLAC__STREAM_DECODER_END_OF_STREAM, FLAC__STREAM_DECODER_ABORTED, FLAC__STREAM_DECODER_UNPARSEABLE_STREAM, FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR,   FLAC__STREAM_DECODER_ALREADY_INITIALIZED, FLAC__STREAM_DECODER_INVALID_CALLBACK, FLAC__STREAM_DECODER_UNINITIALIZED }
enum	FLAC__StreamDecoderReadStatus { FLAC__STREAM_DECODER_READ_STATUS_CONTINUE, FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM, FLAC__STREAM_DECODER_READ_STATUS_ABORT }
enum	FLAC__StreamDecoderWriteStatus { FLAC__STREAM_DECODER_WRITE_STATUS_CONTINUE, FLAC__STREAM_DECODER_WRITE_STATUS_ABORT }
enum	FLAC__StreamDecoderErrorStatus { FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC, FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER, FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH }
Functions
FLAC__StreamDecoder *	FLAC__stream_decoder_new ()
void	FLAC__stream_decoder_delete (FLAC__StreamDecoder *decoder)
FLAC__bool	FLAC__stream_decoder_set_read_callback (FLAC__StreamDecoder *decoder, FLAC__StreamDecoderReadCallback value)
FLAC__bool	FLAC__stream_decoder_set_write_callback (FLAC__StreamDecoder *decoder, FLAC__StreamDecoderWriteCallback value)
FLAC__bool	FLAC__stream_decoder_set_metadata_callback (FLAC__StreamDecoder *decoder, FLAC__StreamDecoderMetadataCallback value)
FLAC__bool	FLAC__stream_decoder_set_error_callback (FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorCallback value)
FLAC__bool	FLAC__stream_decoder_set_client_data (FLAC__StreamDecoder *decoder, void *value)
FLAC__bool	FLAC__stream_decoder_set_metadata_respond (FLAC__StreamDecoder *decoder, FLAC__MetadataType type)
FLAC__bool	FLAC__stream_decoder_set_metadata_respond_application (FLAC__StreamDecoder *decoder, const FLAC__byte id[4])
FLAC__bool	FLAC__stream_decoder_set_metadata_respond_all (FLAC__StreamDecoder *decoder)
FLAC__bool	FLAC__stream_decoder_set_metadata_ignore (FLAC__StreamDecoder *decoder, FLAC__MetadataType type)
FLAC__bool	FLAC__stream_decoder_set_metadata_ignore_application (FLAC__StreamDecoder *decoder, const FLAC__byte id[4])
FLAC__bool	FLAC__stream_decoder_set_metadata_ignore_all (FLAC__StreamDecoder *decoder)
FLAC__StreamDecoderState	FLAC__stream_decoder_get_state (const FLAC__StreamDecoder *decoder)
unsigned	FLAC__stream_decoder_get_channels (const FLAC__StreamDecoder *decoder)
FLAC__ChannelAssignment	FLAC__stream_decoder_get_channel_assignment (const FLAC__StreamDecoder *decoder)
unsigned	FLAC__stream_decoder_get_bits_per_sample (const FLAC__StreamDecoder *decoder)
unsigned	FLAC__stream_decoder_get_sample_rate (const FLAC__StreamDecoder *decoder)
unsigned	FLAC__stream_decoder_get_blocksize (const FLAC__StreamDecoder *decoder)
FLAC__StreamDecoderState	FLAC__stream_decoder_init (FLAC__StreamDecoder *decoder)
void	FLAC__stream_decoder_finish (FLAC__StreamDecoder *decoder)
FLAC__bool	FLAC__stream_decoder_flush (FLAC__StreamDecoder *decoder)
FLAC__bool	FLAC__stream_decoder_reset (FLAC__StreamDecoder *decoder)
FLAC__bool	FLAC__stream_decoder_process_single (FLAC__StreamDecoder *decoder)
FLAC__bool	FLAC__stream_decoder_process_until_end_of_metadata (FLAC__StreamDecoder *decoder)
FLAC__bool	FLAC__stream_decoder_process_until_end_of_stream (FLAC__StreamDecoder *decoder)
Variables
const char *const	FLAC__StreamDecoderStateString []
const char *const	FLAC__StreamDecoderReadStatusString []
const char *const	FLAC__StreamDecoderWriteStatusString []
const char *const	FLAC__StreamDecoderErrorStatusString []

---

Detailed Description

This module contains the functions which implement the stream decoder.

The basic usage of this decoder is as follows:

• The program creates an instance of a decoder using FLAC__stream_decoder_new().
• The program overrides the default settings and sets callbacks for reading, writing, error reporting, and metadata reporting using FLAC__stream_decoder_set_*() functions.
• The program initializes the instance to validate the settings and prepare for decoding using FLAC__stream_decoder_init().
• The program calls the FLAC__stream_decoder_process_*() functions to decode data, which subsequently calls the callbacks.
• The program finishes the decoding with FLAC__stream_decoder_finish(), which flushes the input and output and resets the decoder to the uninitialized state.
• The instance may be used again or deleted with FLAC__stream_decoder_delete().

In more detail, the program will create a new instance by calling FLAC__stream_decoder_new(), then call FLAC__stream_decoder_set_*() functions to set the callbacks and client data, and call FLAC__stream_decoder_init(). The required callbacks are:

• Read callback - This function will be called when the decoder needs more input data. The address of the buffer to be filled is supplied, along with the number of bytes the buffer can hold. The callback may choose to supply less data and modify the byte count but must be careful not to overflow the buffer. The callback then returns a status code chosen from FLAC__StreamDecoderReadStatus.
• Write callback - This function will be called when the decoder has decoded a single frame of data. The decoder will pass the frame metadata as well as an array of pointers (one for each channel) pointing to the decoded audio.
• Metadata callback - This function will be called when the decoder has decoded a metadata block. In a valid FLAC file there will always be one STREAMINFO block, followed by zero or more other metadata blocks. These will be supplied by the decoder in the same order as they appear in the stream and always before the first audio frame (i.e. write callback). The metadata block that is passed in must not be modified, and it doesn't live beyond the callback, so you should make a copy of it with FLAC__metadata_object_clone() if you will need it elsewhere. Since metadata blocks can potentially be large, by default the decoder only calls the metadata callback for the STREAMINFO block; you can instruct the decoder to pass or filter other blocks with FLAC__stream_decoder_set_metadata_*() calls.
• Error callback - This function will be called whenever an error occurs during decoding.

Once the decoder is initialized, your program will call one of several functions to start the decoding process:

• FLAC__stream_decoder_process_single() - Tells the decoder to process at most one metadata block or audio frame and return, calling either the metadata callback or write callback, respectively, once. If the decoder loses sync it will return with only the error callback being called.
• FLAC__stream_decoder_process_until_end_of_metadata() - Tells the decoder to process the stream from the current location and stop upon reaching the first audio frame. The user will get one metadata, write, or error callback per metadata block, audio frame, or sync error, respectively.
• FLAC__stream_decoder_process_until_end_of_stream() - Tells the decoder to process the stream from the current location until the read callback returns FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM or FLAC__STREAM_DECODER_READ_STATUS_ABORT. The user will get one metadata, write, or error callback per metadata block, audio frame, or sync error, respectively.

When the decoder has finished decoding (normally or through an abort), the instance is finished by calling FLAC__stream_decoder_finish(), which ensures the decoder is in the correct state and frees memory. Then the instance may be deleted with FLAC__stream_decoder_delete() or initialized again to decode another stream.

Note that the stream decoder has no real concept of stream position, it just converts data. To seek within a stream the callbacks have only to flush the decoder using FLAC__stream_decoder_flush() and start feeding data from the new position through the read callback. The seekable stream decoder does just this.

The FLAC__stream_decoder_set_metadata_*() functions deserve special attention. By default, the decoder only calls the metadata_callback for the STREAMINFO block. These functions allow you to tell the decoder explicitly which blocks to parse and return via the metadata_callback and/or which to skip. Use a FLAC__stream_decoder_set_metadata_respond_all(), FLAC__stream_decoder_set_metadata_ignore() ... or FLAC__stream_decoder_set_metadata_ignore_all(), FLAC__stream_decoder_set_metadata_respond() ... sequence to exactly specify which blocks to return. Remember that some metadata blocks can be big so filtering out the ones you don't use can reduce the memory requirements of the decoder. Also note the special forms FLAC__stream_decoder_set_metadata_respond_application(id) and FLAC__stream_decoder_set_metadata_ignore_application(id) for filtering APPLICATION blocks based on the application ID.

STREAMINFO and SEEKTABLE blocks are always parsed and used internally, but they still can legally be filtered from the metadata_callback.

Note:

The "set" functions may only be called when the decoder is in the state FLAC__STREAM_DECODER_UNINITIALIZED, i.e. after FLAC__stream_decoder_new() or FLAC__stream_decoder_finish(), but before FLAC__stream_decoder_init(). If this is the case they will return true, otherwise false.

Note:

FLAC__stream_decoder_finish() resets all settings to the constructor defaults, including the callbacks.

---

Typedef Documentation

typedef FLAC__StreamDecoderReadStatus(* FLAC__StreamDecoderReadCallback)(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data)

Signature for the read callback. See FLAC__stream_decoder_set_read_callback() for more info. Parameters: decoder  The decoder instance calling the callback. buffer  A pointer to a location for the callee to store data to be decoded. bytes  A pointer to the size of the buffer. On entry to the callback, it contains the maximum number of bytes that may be stored in buffer. The callee must set it to the actual number of bytes stored before returning. client_data  The callee's client data set through FLAC__stream_decoder_set_client_data(). Return values: FLAC__StreamDecoderReadStatus  The callee's return status.

typedef FLAC__StreamDecoderWriteStatus(* FLAC__StreamDecoderWriteCallback)(const FLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data)

Signature for the write callback. See FLAC__stream_decoder_set_write_callback() for more info. Parameters: decoder  The decoder instance calling the callback. frame  The description of the decoded frame. See FLAC__Frame. buffer  An array of pointers to decoded channels of data. Each pointer will point to an array of signed samples of length frame->header.blocksize. Currently, the channel order has no meaning except for stereo streams; in this case channel 0 is left and 1 is right. client_data  The callee's client data set through FLAC__stream_decoder_set_client_data(). Return values: FLAC__StreamDecoderWriteStatus  The callee's return status.

typedef void(* FLAC__StreamDecoderMetadataCallback)(const FLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data)

Signature for the metadata callback. See FLAC__stream_decoder_set_metadata_callback() for more info. Parameters: decoder  The decoder instance calling the callback. metadata  The decoded metadata block. client_data  The callee's client data set through FLAC__stream_decoder_set_client_data().

typedef void(* FLAC__StreamDecoderErrorCallback)(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data)

Signature for the error callback. See FLAC__stream_decoder_set_error_callback() for more info. Parameters: decoder  The decoder instance calling the callback. status  The error encountered by the decoder. client_data  The callee's client data set through FLAC__stream_decoder_set_client_data().

---

Enumeration Type Documentation

enum FLAC__StreamDecoderState

State values for a FLAC__StreamDecoder The decoder's state can be obtained by calling FLAC__stream_decoder_get_state(). Enumeration values: FLAC__STREAM_DECODER_SEARCH_FOR_METADATA  The decoder is ready to search for metadata. FLAC__STREAM_DECODER_READ_METADATA  The decoder is ready to or is in the process of reading metadata. FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC  The decoder is ready to or is in the process of searching for the frame sync code. FLAC__STREAM_DECODER_READ_FRAME  The decoder is ready to or is in the process of reading a frame. FLAC__STREAM_DECODER_END_OF_STREAM  The decoder has reached the end of the stream. FLAC__STREAM_DECODER_ABORTED  The decoder was aborted by the read callback. FLAC__STREAM_DECODER_UNPARSEABLE_STREAM  The decoder encountered reserved fields in use in the stream. FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR  An error occurred allocating memory. FLAC__STREAM_DECODER_ALREADY_INITIALIZED  FLAC__stream_decoder_init() was called when the decoder was already initialized, usually because FLAC__stream_decoder_finish() was not called. FLAC__STREAM_DECODER_INVALID_CALLBACK  FLAC__stream_decoder_init() was called without all callbacks being set. FLAC__STREAM_DECODER_UNINITIALIZED  The decoder is in the uninitialized state.

enum FLAC__StreamDecoderReadStatus

Return values for the FLAC__StreamDecoder read callback. Enumeration values: FLAC__STREAM_DECODER_READ_STATUS_CONTINUE  The read was OK and decoding can continue. FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM  The read was attempted at the end of the stream. FLAC__STREAM_DECODER_READ_STATUS_ABORT  An unrecoverable error occurred. The decoder will return from the process call.

enum FLAC__StreamDecoderWriteStatus

Return values for the FLAC__StreamDecoder write callback. Enumeration values: FLAC__STREAM_DECODER_WRITE_STATUS_CONTINUE  The write was OK and decoding can continue. FLAC__STREAM_DECODER_WRITE_STATUS_ABORT  An unrecoverable error occurred. The decoder will return from the process call.

enum FLAC__StreamDecoderErrorStatus

Possible values passed in to the FLAC__StreamDecoder error callback. Enumeration values: FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC  An error in the stream caused the decoder to lose synchronization. FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER  The decoder encountered a corrupted frame header. FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH  The frame's data did not match the CRC in the footer.

---

Function Documentation

FLAC__StreamDecoder* FLAC__stream_decoder_new (    )

Create a new stream decoder instance. The instance is created with default settings; see the individual FLAC__stream_decoder_set_*() functions for each setting's default. Return values: FLAC__StreamDecoder  * NULL if there was an error allocating memory, else the new instance.

void FLAC__stream_decoder_delete (  FLAC__StreamDecoder *    decoder )

Free a decoder instance. Deletes the object pointed to by decoder. Parameters: decoder  A pointer to an existing decoder. Assertions: decoder != NULL

FLAC__bool FLAC__stream_decoder_set_read_callback (  FLAC__StreamDecoder *    decoder, FLAC__StreamDecoderReadCallback    value )

Set the read callback. The supplied function will be called when the decoder needs more input data. The address of the buffer to be filled is supplied, along with the number of bytes the buffer can hold. The callback may choose to supply less data and modify the byte count but must be careful not to overflow the buffer. The callback then returns a status code chosen from FLAC__StreamDecoderReadStatus. Note: The callback is mandatory and must be set before initialization. Default Value: NULL Parameters: decoder  A decoder instance to set. value  See above. Assertions: decoder != NULL value != NULL Return values: FLAC__bool  false if the decoder is already initialized, else true.

FLAC__bool FLAC__stream_decoder_set_write_callback (  FLAC__StreamDecoder *    decoder, FLAC__StreamDecoderWriteCallback    value )

Set the write callback. The supplied function will be called when the decoder has decoded a single frame of data. The decoder will pass the frame metadata as well as an array of pointers (one for each channel) pointing to the decoded audio. Note: The callback is mandatory and must be set before initialization. Default Value: NULL Parameters: decoder  A decoder instance to set. value  See above. Assertions: decoder != NULL value != NULL Return values: FLAC__bool  false if the decoder is already initialized, else true.

FLAC__bool FLAC__stream_decoder_set_metadata_callback (  FLAC__StreamDecoder *    decoder, FLAC__StreamDecoderMetadataCallback    value )

Set the metadata callback. The supplied function will be called when the decoder has decoded a metadata block. In a valid FLAC file there will always be one STREAMINFO block, followed by zero or more other metadata blocks. These will be supplied by the decoder in the same order as they appear in the stream and always before the first audio frame (i.e. write callback). The metadata block that is passed in must not be modified, and it doesn't live beyond the callback, so you should make a copy of it with FLAC__metadata_object_clone() if you will need it elsewhere. Since metadata blocks can potentially be large, by default the decoder only calls the metadata callback for the STREAMINFO block; you can instruct the decoder to pass or filter other blocks with FLAC__stream_decoder_set_metadata_*() calls. Note: The callback is mandatory and must be set before initialization. Default Value: NULL Parameters: decoder  A decoder instance to set. value  See above. Assertions: decoder != NULL value != NULL Return values: FLAC__bool  false if the decoder is already initialized, else true.

FLAC__bool FLAC__stream_decoder_set_error_callback (  FLAC__StreamDecoder *    decoder, FLAC__StreamDecoderErrorCallback    value )

Set the error callback. The supplied function will be called whenever an error occurs during decoding. Note: The callback is mandatory and must be set before initialization. Default Value: NULL Parameters: decoder  A decoder instance to set. value  See above. Assertions: decoder != NULL value != NULL Return values: FLAC__bool  false if the decoder is already initialized, else true.

FLAC__bool FLAC__stream_decoder_set_client_data (  FLAC__StreamDecoder *    decoder, void *    value )

Set the client data to be passed back to callbacks. This value will be supplied to callbacks in their client_data argument. Default Value: NULL Parameters: decoder  A decoder instance to set. value  See above. Assertions: decoder != NULL Return values: FLAC__bool  false if the decoder is already initialized, else true.

FLAC__bool FLAC__stream_decoder_set_metadata_respond (  FLAC__StreamDecoder *    decoder, FLAC__MetadataType    type )

Direct the decoder to pass on all metadata blocks of type type. Default Value: By default, only the STREAMINFO block is returned via the metadata callback. Parameters: decoder  A decoder instance to set. type  See above. Assertions: decoder != NULL type is valid Return values: FLAC__bool  false if the decoder is already initialized, else true.

FLAC__bool FLAC__stream_decoder_set_metadata_respond_application (  FLAC__StreamDecoder *    decoder, const FLAC__byte    id[4] )

Direct the decoder to pass on all APPLICATION metadata blocks of the given id. Default Value: By default, only the STREAMINFO block is returned via the metadata callback. Parameters: decoder  A decoder instance to set. id  See above. Assertions: decoder != NULL id != NULL Return values: FLAC__bool  false if the decoder is already initialized, else true.

FLAC__bool FLAC__stream_decoder_set_metadata_respond_all (  FLAC__StreamDecoder *    decoder )

Direct the decoder to pass on all metadata blocks of any type. Default Value: By default, only the STREAMINFO block is returned via the metadata callback. Parameters: decoder  A decoder instance to set. Assertions: decoder != NULL Return values: FLAC__bool  false if the decoder is already initialized, else true.

FLAC__bool FLAC__stream_decoder_set_metadata_ignore (  FLAC__StreamDecoder *    decoder, FLAC__MetadataType    type )

Direct the decoder to filter out all metadata blocks of type type. Default Value: By default, only the STREAMINFO block is returned via the metadata callback. Parameters: decoder  A decoder instance to set. type  See above. Assertions: decoder != NULL type is valid Return values: FLAC__bool  false if the decoder is already initialized, else true.

FLAC__bool FLAC__stream_decoder_set_metadata_ignore_application (  FLAC__StreamDecoder *    decoder, const FLAC__byte    id[4] )

Direct the decoder to filter out all APPLICATION metadata blocks of the given id. Default Value: By default, only the STREAMINFO block is returned via the metadata callback. Parameters: decoder  A decoder instance to set. id  See above. Assertions: decoder != NULL id != NULL Return values: FLAC__bool  false if the decoder is already initialized, else true.

FLAC__bool FLAC__stream_decoder_set_metadata_ignore_all (  FLAC__StreamDecoder *    decoder )

Direct the decoder to filter out all metadata blocks of any type. Default Value: By default, only the STREAMINFO block is returned via the metadata callback. Parameters: decoder  A decoder instance to set. Assertions: decoder != NULL Return values: FLAC__bool  false if the decoder is already initialized, else true.

FLAC__StreamDecoderState FLAC__stream_decoder_get_state (  const FLAC__StreamDecoder *    decoder )

Get the current decoder state. Parameters: decoder  A decoder instance to query. Assertions: decoder != NULL Return values: FLAC__StreamDecoderState  The current decoder state.

unsigned FLAC__stream_decoder_get_channels (  const FLAC__StreamDecoder *    decoder )

Get the current number of channels in the stream being decoded. Will only be valid after decoding has started and will contain the value from the most recently decoded frame header. Parameters: decoder  A decoder instance to query. Assertions: decoder != NULL Return values: unsigned  See above.

FLAC__ChannelAssignment FLAC__stream_decoder_get_channel_assignment (  const FLAC__StreamDecoder *    decoder )

Get the current channel assignment in the stream being decoded. Will only be valid after decoding has started and will contain the value from the most recently decoded frame header. Parameters: decoder  A decoder instance to query. Assertions: decoder != NULL Return values: FLAC__ChannelAssignment  See above.

unsigned FLAC__stream_decoder_get_bits_per_sample (  const FLAC__StreamDecoder *    decoder )

Get the current sample resolution in the stream being decoded. Will only be valid after decoding has started and will contain the value from the most recently decoded frame header. Parameters: decoder  A decoder instance to query. Assertions: decoder != NULL Return values: unsigned  See above.

unsigned FLAC__stream_decoder_get_sample_rate (  const FLAC__StreamDecoder *    decoder )

Get the current sample rate in Hz of the stream being decoded. Will only be valid after decoding has started and will contain the value from the most recently decoded frame header. Parameters: decoder  A decoder instance to query. Assertions: decoder != NULL Return values: unsigned  See above.

unsigned FLAC__stream_decoder_get_blocksize (  const FLAC__StreamDecoder *    decoder )

Get the current blocksize of the stream being decoded. Will only be valid after decoding has started and will contain the value from the most recently decoded frame header. Parameters: decoder  A decoder instance to query. Assertions: decoder != NULL Return values: unsigned  See above.

FLAC__StreamDecoderState FLAC__stream_decoder_init (  FLAC__StreamDecoder *    decoder )

Initialize the decoder instance. Should be called after FLAC__stream_decoder_new() and FLAC__stream_decoder_set_*() but before any of the FLAC__stream_decoder_process_*() functions. Will set and return the decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA if initialization succeeded. Parameters: decoder  An uninitialized decoder instance. Assertions: decoder != NULL Return values: FLAC__StreamDecoderState  FLAC__STREAM_DECODER_SEARCH_FOR_MEATADATA if initialization was successful; see FLAC__StreamDecoderState for the meanings of other return values.

void FLAC__stream_decoder_finish (  FLAC__StreamDecoder *    decoder )

Finish the decoding process. Flushes the decoding buffer, releases resources, resets the decoder settings to their defaults, and returns the decoder state to FLAC__STREAM_DECODER_UNINITIALIZED. In the event of a prematurely-terminated decode, it is not strictly necessary to call this immediately before FLAC__stream_decoder_delete() but it is good practice to match every FLAC__stream_decoder_init() with a FLAC__stream_decoder_finish(). Parameters: decoder  An uninitialized decoder instance. Assertions: decoder != NULL

FLAC__bool FLAC__stream_decoder_flush (  FLAC__StreamDecoder *    decoder )

Flush the stream input. The decoder's input buffer will be cleared and the state set to FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC. Parameters: decoder  A decoder instance. Assertions: decoder != NULL Return values: FLAC__bool  true if successful, else false if a memory allocation error occurs.

FLAC__bool FLAC__stream_decoder_reset (  FLAC__StreamDecoder *    decoder )

Reset the decoding process. The decoder's input buffer will be cleared and the state set to FLAC__STREAM_DECODER_SEARCH_FOR_METADATA. This is similar to FLAC__stream_decoder_finish() except that the settings are preserved; there is no need to call FLAC__stream_decoder_init() before decoding again. Parameters: decoder  A decoder instance. Assertions: decoder != NULL Return values: FLAC__bool  true if successful, else false if a memory allocation error occurs.

FLAC__bool FLAC__stream_decoder_process_single (  FLAC__StreamDecoder *    decoder )

Decode one metadata block or audio frame. This version instructs the decoder to decode a either a single metadata block or a single frame and stop, unless the callbacks return a fatal error or the read callback returns FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM. As the decoder needs more input it will call the read callback. Depending on what was decoded, the metadata or write callback will be called with the decoded metadata block or audio frame, unless an error occurred. If the decoder loses sync it will call the error callback instead. Parameters: decoder  An initialized decoder instance in the state FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC. Assertions: decoder != NULL FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC Return values: FLAC__bool  false if any read or write error occurred (except FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else true; in any case, check the decoder state with FLAC__stream_decoder_get_state() to see what went wrong or to check for lost synchronization (a sign of stream corruption).

FLAC__bool FLAC__stream_decoder_process_until_end_of_metadata (  FLAC__StreamDecoder *    decoder )

Decode until the end of the metadata. This version instructs the decoder to decode from the current position and continue until all the metadata has been read, or until the callbacks return a fatal error or the read callback returns FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM. As the decoder needs more input it will call the read callback. As each metadata block is decoded, the metadata callback will be called with the decoded metadata. If the decoder loses sync it will call the error callback. Parameters: decoder  An initialized decoder instance in the state FLAC__STREAM_DECODER_SEARCH_FOR_METADATA. Assertions: decoder != NULL FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_METADATA Return values: FLAC__bool  false if any read or write error occurred (except FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else true; in any case, check the decoder state with FLAC__stream_decoder_get_state() to see what went wrong or to check for lost synchronization (a sign of stream corruption).

FLAC__bool FLAC__stream_decoder_process_until_end_of_stream (  FLAC__StreamDecoder *    decoder )

Decode until the end of the stream. This version instructs the decoder to decode from the current position and continue until the end of stream (the read callback returns FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM), or until the callbacks return a fatal error. As the decoder needs more input it will call the read callback. As each metadata block and frame is decoded, the metadata or write callback will be called with the decoded metadata or frame. If the decoder loses sync it will call the error callback. Parameters: decoder  An initialized decoder instance in the state FLAC__STREAM_DECODER_SEARCH_FOR_METADATA. Assertions: decoder != NULL FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_METADATA Return values: FLAC__bool  false if any read or write error occurred (except FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else true; in any case, check the decoder state with FLAC__stream_decoder_get_state() to see what went wrong or to check for lost synchronization (a sign of stream corruption).

---

Variable Documentation

const char* const FLAC__StreamDecoderStateString[]

Maps a FLAC__StreamDecoderState to a C string. Using a FLAC__StreamDecoderState as the index to this array will give the string equivalent. The contents should not be modified.

const char* const FLAC__StreamDecoderReadStatusString[]

Maps a FLAC__StreamDecoderReadStatus to a C string. Using a FLAC__StreamDecoderReadStatus as the index to this array will give the string equivalent. The contents should not be modified.

const char* const FLAC__StreamDecoderWriteStatusString[]

Maps a FLAC__StreamDecoderWriteStatus to a C string. Using a FLAC__StreamDecoderWriteStatus as the index to this array will give the string equivalent. The contents should not be modified.

const char* const FLAC__StreamDecoderErrorStatusString[]

Maps a FLAC__StreamDecoderErrorStatus to a C string. Using a FLAC__StreamDecoderErrorStatus as the index to this array will give the string equivalent. The contents should not be modified.

---